<h2>DESCRIPTION</h2>

<em>v.colors</em> allows creating or modifying color table associated
with a vector map similarly
to <em><a href="r.colors.html">r.colors</a></em> for raster maps.

<p>Color rules are built from features category values
(<b>use=cat</b>) or numeric data column (<b>use=attr</b>) defined
by <b>column</b> option. For 3D vector maps is allowed to define color
rules based on points or centroids z-coordinate (<b>use=z</b>). 3D
vector lines are not supported.

<p>The <b>raster</b> option allows user to specify a raster map from
which to copy the color table, similarly <b>raster_3d</b> option for 3D
raster map. Without <b>use=attr</b> and <b>column</b> options, raster values
will be matched with categories. Use these two options to transfer raster
colors to vector attributes.

<p>The <b>rules</b> color table type will cause <em>v.colors</em> to
read color table specifications from given file and will build the
color table accordingly. See
<em><a href="r.colors.html">r.colors</a></em> manual page for details.

<p>If the user specifies the <b>-w</b> flag, the current color table
file for the input map will not be overwritten. This means that the
color table is created only if the vector map does not already have a
color table. If this option is not specified, the color table will be
created if one does not exist, or modified if it does.

<p>Alternatively the color rules can be stored in a string column
(<b>rgb_column</b>) by saving the RRR:GGG:BBB values suitable for use
with <em><a href="d.vect.html">d.vect</a></em>.

<h2>NOTES</h2>

For vector maps with a large number of features it's more convenient
to store color rules in an attribute column (given by <b>rgb_column</b>)
rather then in a color table file. Reading color tables with more then 1000
items is slow.

<h2>EXAMPLES</h2>

<h3>Define color table based on categories</h3>

Define color table <tt>wave</tt> based on categories from layer 1

<div class="code"><pre>
v.colors map=soils_general layer=1 color=wave
</pre></div>

<h3>Define color table based on attribute values</h3>

Define color table <tt>ryg</tt> based on values from attribute
column <tt>AREA</tt>. Attribute table is linked to layer 1.

<div class="code"><pre>
v.to.db map=soils_general layer=1 option=area column=AREA
v.colors map=soils_general layer=1 color=wave use=attr column=AREA
</pre></div>

<h3>Define color table stored as RGB values in attribute table</h3>

Write color values to the attribute table (column <tt>GRASSRGB</tt>)
instead of creating color table.

<div class="code"><pre>
v.colors map=soils_general layer=1 color=wave use=attr column=AREA rgb_column=GRASSRGB

# See some GRASSRGB values:
v.db.select map=soils_general where="cat &lt; 4"
cat|OBJECTID|AREA|PERIMETER|GSLNC250_|GSLNC250_I|GSL_NAME|GRASSRGB
1|1|0|164616.125|2|1|NC113|212:42:127
2|2|0|30785.529297|3|2|NC096|212:42:127
3|3|0|87572.882812|4|3|NC097|212:42:127
</pre></div>

<h3>Convert RGB attribute values into color table</h3>

Convert existing RGB values to color table rules.

<div class="code"><pre>
v.colors -c map=soils_general rgb_column=GRASSRGB
</pre></div>

Note that in this case the vector map has a proper color table
assigned (check
by <em><a href="v.colors.out.html">v.colors.out</a></em>) together
with GRASSRGB attribute column. Also note that color table is preferred
over RGB values stored in attribute table.

<h3>Transfer raster colors to vector</h3>

<div class="code"><pre>
# create an example raster from census blocks (10m pixel resolution)
g.region vector=censusblk_swwake res=10 -ap
v.to.rast input=censusblk_swwake use=attr attribute_column=TOTAL_POP output=censusblk_swwake_total_pop
r.colors -e map=censusblk_swwake_total_pop color=blues

# transfer raster colors to vector attributes (raster values to attributes)
r.colors.out map=censusblk_swwake_total_pop rules=- | v.colors map=censusblk_swwake use=attr column=TOTAL_POP rules=-
# equivalent, but simpler
v.colors map=censusblk_swwake use=attr column=TOTAL_POP raster=censusblk_swwake_total_pop

# transfer raster colors to vector categories (raster values to categories)
v.colors map=censusblk_swwake raster=censusblk_swwake_total_pop
</pre></div>

<h3>Remove existing color table</h3>

<p>
Existing color table can be removed by <b>-r</b> flag.

<div class="code"><pre>
v.colors -r map=soils_general
</pre></div>

Before removing color table you can store color rules to the file
by <em><a href="v.colors.out.html">v.colors.out</a></em> and later to
assign by <b>rules</b> option.

<div class="code"><pre>
v.colors.out map=soils_general rules=soils.colr
v.colors map=soils_general rules=soils.colr
</pre></div>

To drop RGB column
use <em><a href="v.db.dropcolumn.html">v.db.dropcolumn</a></em>.

<div class="code"><pre>
v.db.dropcolumn map=soils_general column=GRASSRGB
</pre></div>

<h2>SEE ALSO</h2>

<em>
<a href="d.vect.html">d.vect</a>,
<a href="r.colors.html">r.colors</a>,
<a href="r.colors.out.html">r.colors.out</a>,
<a href="r3.colors.html">r3.colors</a>,
<a href="r3.colors.out.html">r3.colors.out</a>,
<a href="v.colors.out.html">v.colors.out</a>
</em>

<p>See also wiki
page <a href="https://grasswiki.osgeo.org/wiki/Color_tables">Color
tables</a> (from GRASS User Wiki)

<p><a href="http://colorbrewer.org">ColorBrewer</a> is an online tool designed to
help people select good color schemes for maps and other graphics.

<h2>AUTHORS</h2>

Martin Landa, OSGeoREL, Czech Technical University in Prague, Czech Republic<br>
Huidae Cho

<!--
<p>
<i>Last changed: $Date$</i>
-->
